docs(rfc): 插件扩展面盘点与边界（RFC 0011） - #385

Revise RFC 0012's event API: instead of narrowing Cordis's five dispatch
modes down to three, keep all of them under their original names and move
the restrictions onto the event definition, where they can be checked
mechanically at define time.

Three earlier exclusions were wrong:

- `emit` was dropped by over-generalising "hook events cross a process
  boundary" to "all events do". Plugin-to-plugin events live in one
  runtime, where synchronous dispatch is both valid and preferable.
- `parallel` and `serial` were folded together on the premise that awaiting
  is the dispatcher's choice. That conflated two things: the real
  distinction is whether listeners can observe each other's side effects,
  which is a property of the event, not the call site.
- `bail` was banned for a real hazard applied too broadly. First-responder
  resolution is legitimate; only permission adjudication is unsafe, and
  that already has `decide`.

Constraints now: `emit` cannot be cross-process, and `security: true`
events accept only `decide`. Keeping Cordis's names also restores full
mode parity with DSH apart from `tools/pre-execute`, which is
`security: true` and therefore `decide` on our side.

Docs only; no runtime behaviour changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

The constraint stands but the stated reason was wrong. "Cross-process
cannot dispatch synchronously" is inaccurate: Atomics.wait() over a
SharedArrayBuffer with receiveMessageOnPort() gives real synchronous
blocking between worker_threads, and Node permits Atomics.wait on the
main thread. Only true separate processes are impractical, since a
SharedArrayBuffer cannot cross an IPC pipe.

The actual reason is semantic redundancy. What `emit` buys — no microtask
scheduling, listener on the dispatcher's stack so exceptions propagate
directly, deterministic uninterleaved order — is entirely lost once a
process boundary is crossed: the IPC round trip dwarfs scheduling cost,
the stack is already severed and errors must be serialised, and ordering
comes from serial transport rather than synchronous semantics. A blocking
notification is precisely `serial`, which already exists.

This rationale is transport-independent, so it survives a future move of
the hook worker from child_process to worker_threads.

Docs only; no runtime behaviour changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

The plugin system had no entry under .oo/rules/ — its normative content
was scattered across three RFC series, a hand-written usage doc, and the
code. Establish .oo/rules/PLUGIN-SYSTEM.md plus a plugin-system/ directory
following the same shape as HOOKS.md, so rules carry the specification and
RFCs stay as the record of why each decision was made.

This commit lands the entry, the overview, and the communication chapter.
The overview doubles as a gap map: every capability is tagged implemented,
in-design, or missing, so nobody writes plugins against a design.

Four inconsistencies surfaced while writing it, all recorded in the
overview:

- executeCommand accepts a scoped <scope>/<id> and will HTTP to another
  plugin's server command, while the usage doc describes only the
  same-scope path
- client can reach across plugins but server cannot: invokeChannel binds
  the scope host-side, so a server plugin only ever calls its own channel
- RFC 0012's three-level availability grading is coarser than reality —
  hooks/events.md already carries a per-adapter, per-event matrix with a
  canBlock dimension, and the event spec should defer to it
- same-scope command id collisions remain unverified

Remaining chapters are listed as pending rather than linked, so the index
has no dead links.

Docs only; no runtime behaviour changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

The spec was accumulating chapters without a spine — twelve documents
across two RFC series and a rules directory, each capability argued
separately, no single sentence saying what a plugin is. Give it one.

A plugin stands in exactly three relations to the host and to other
plugins, distinguished by who owns the result:

- contribute — hands over data, the receiver decides how to use it
- participate — gets called inside someone else's flow, the host merges
- provide — exposes a named capability, the plugin itself decides

The three are mutually exclusive and complete, so a new capability must
classify into one; if it doesn't, the model is wrong and changes first.
Crossed with where code runs (client / server / reporter), this yields a
matrix where the blanks are the gaps, and it reframes the open work in
one line each:

- contribute is healthy on both ends
- participate sits in the wrong place: it belongs on the resident server
  but currently runs in the reporter subprocess with a logger-only ctx,
  which is exactly what RFC 0012 moves
- provide is crippled server-side, since channels and registerApi bind
  scope host-side and a server plugin can only ever call its own

Chapters now follow the model: contribute.md, participate.md, provide.md
replace the earlier communication.md, whose content spanned two relations
and so obscured the distinction.

Docs only; no runtime behaviour changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

The mode constraint table only covered participate-type channels, but
transport reachability and security grading are properties of every
communication channel, not just events.

- README: define `transport` and a three-tier `security` grading, plus
  where the security property attaches per relation (channel for
  contribute/participate, ctx capability surface for provide)
- contribute: asset directories are `advisory`, not `none` — skills and
  rules reach the system prompt, mcp reaches the toolset
- provide: provide-type channels carry no `security` field; the handler
  is the plugin's own code, so the real bound is what ctx exposes
- participate: frame the mode table as a specialization of the general
  rule rather than a standalone invention

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

README and provide.md both assert that the real bound on a plugin is the
ctx capability surface, with nothing behind the claim. This writes that
chapter.

The starting point is that there is no sandbox: client, server, and the
hook reporter all load plugin code through a plain dynamic import into
the host's own module graph. So "plugins cannot X" throughout the spec
means the host offers no channel for X, not that the host prevents it.

Documents the four boundaries that are real — the first-party capability
gate in createServerContext, the source-group whitelist that gate rests
on, the realpath-based scoped path check, and the loopback-only proxy
with credential header stripping — plus the build-time source boundary
and diagnostic redaction. Adds the review checklist for new ctx
capabilities, and an explicit list of guarantees we do not make.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo

RFC 0011 surveyed the extension surface, 0012 converged hooks, and the
rules spec wrote both down. All three describe; none of them made any
code smaller. plugin-registry.ts still carries nine near-identical scope
filters, two separate pending queues, and contract checking in exactly
one place.

The kernel is one law: every named collection has a single end and a
many end, and the definer always holds the single end. Registry gives
the definer read and everyone contribute; event gives the definer emit
and everyone on; api gives the definer provide and everyone invoke. The
three relations stop being a taxonomy we declared and become a
consequence of who defined the collection.

Ownership, pending/drain, and contract checking move onto the collection
itself, so a new channel cannot forget them. `onAvailable` and the
`command` type both disappear — the first because waiting is now a
kernel property, the second because it is an api missing exactly the
four things collections provide by default.

Two edges stay deliberately outside: ctx construction and participant
instantiation. Admitting either is Cordis, and costs the guarantee that
the host baseline is the floor.

Includes the full interface surface and a six-phase migration where
phases 1-4 leave every existing plugin contract untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014uDzTTAD3QqpHS8SHgRWEo